summaryrefslogtreecommitdiffstats
path: root/documentation/bsp-guide/bsp.xml
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-03-08 12:10:22 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-03-25 09:41:12 +0100
commitc130396f0003e5ae5c03620ae979f48b1d898c33 (patch)
treee438702db55fc7eeb321f04497b6ade684cd45a6 /documentation/bsp-guide/bsp.xml
parentc8b2ba7523afd1611e7afb3d83b6df5c3df8326f (diff)
downloadpoky-c130396f0003e5ae5c03620ae979f48b1d898c33.tar.gz
bsp-guide: Updates to Reqs and Recommeds for released BSPs
Updated this section with minor edits. (From yocto-docs rev: 1bc1dcda5fbab4a66737653164222f4fc5a7289c) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/bsp-guide/bsp.xml')
-rw-r--r--documentation/bsp-guide/bsp.xml320
1 files changed, 198 insertions, 122 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 45905f8b6b..72b065dad3 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -1171,175 +1171,251 @@
1171 <title>Requirements and Recommendations for Released BSPs</title> 1171 <title>Requirements and Recommendations for Released BSPs</title>
1172 1172
1173 <para> 1173 <para>
1174 Certain requirements exist for a released BSP to be considered 1174 Certain requirements exist for a released BSP to be
1175 compliant with the Yocto Project. 1175 considered compliant with the Yocto Project.
1176 Additionally, recommendations also exist. 1176 Additionally, recommendations also exist.
1177 This section describes the requirements and recommendations for 1177 This section describes the requirements and
1178 released BSPs. 1178 recommendations for released BSPs.
1179 </para> 1179 </para>
1180 1180
1181 <section id='released-bsp-requirements'> 1181 <section id='released-bsp-requirements'>
1182 <title>Released BSP Requirements</title> 1182 <title>Released BSP Requirements</title>
1183 1183
1184 <para> 1184 <para>
1185 Before looking at BSP requirements, you should consider the following: 1185 Before looking at BSP requirements, you should consider
1186 the following:
1186 <itemizedlist> 1187 <itemizedlist>
1187 <listitem><para>The requirements here assume the BSP layer is a well-formed, "legal" 1188 <listitem><para>
1188 layer that can be added to the Yocto Project. 1189 The requirements here assume the BSP layer
1189 For guidelines on creating a layer that meets these base requirements, see the 1190 is a well-formed, "legal" layer that can be
1190 "<link linkend='bsp-layers'>BSP Layers</link>" and the 1191 added to the Yocto Project.
1191 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding 1192 For guidelines on creating a layer that meets
1192 and Creating Layers"</ulink> in the Yocto Project Development Tasks Manual. 1193 these base requirements, see the
1194 "<link linkend='bsp-layers'>BSP Layers</link>"
1195 section in this manual and the
1196 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers"</ulink>"
1197 section in the Yocto Project Development Tasks
1198 Manual.
1193 </para></listitem> 1199 </para></listitem>
1194 <listitem><para>The requirements in this section apply regardless of how you 1200 <listitem><para>
1195 package a BSP. 1201 The requirements in this section apply
1196 You should consult the packaging and distribution guidelines for your 1202 regardless of how you package a BSP.
1197 specific release process. 1203 You should consult the packaging and distribution
1198 For an example of packaging and distribution requirements, see the 1204 guidelines for your specific release process.
1205 For an example of packaging and distribution
1206 requirements, see the
1199 "<ulink url='https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process'>Third Party BSP Release Process</ulink>" 1207 "<ulink url='https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process'>Third Party BSP Release Process</ulink>"
1200 wiki page. 1208 wiki page.
1201 </para></listitem> 1209 </para></listitem>
1202 <listitem><para>The requirements for the BSP as it is made available to a developer 1210 <listitem><para>
1203 are completely independent of the released form of the BSP. 1211 The requirements for the BSP as it is made
1204 For example, the BSP Metadata can be contained within a Git repository 1212 available to a developer are completely
1205 and could have a directory structure completely different from what appears 1213 independent of the released form of the BSP.
1214 For example, the BSP Metadata can be contained
1215 within a Git repository and could have a directory
1216 structure completely different from what appears
1206 in the officially released BSP layer. 1217 in the officially released BSP layer.
1207 </para></listitem> 1218 </para></listitem>
1208 <listitem><para>It is not required that specific packages or package 1219 <listitem><para>
1209 modifications exist in the BSP layer, beyond the requirements for general 1220 It is not required that specific packages or
1221 package modifications exist in the BSP layer,
1222 beyond the requirements for general
1210 compliance with the Yocto Project. 1223 compliance with the Yocto Project.
1211 For example, no requirement exists dictating that a specific kernel or 1224 For example, no requirement exists dictating
1212 kernel version be used in a given BSP. 1225 that a specific kernel or kernel version be
1226 used in a given BSP.
1213 </para></listitem> 1227 </para></listitem>
1214 </itemizedlist> 1228 </itemizedlist>
1215 </para> 1229 </para>
1216 1230
1217 <para> 1231 <para>
1218 Following are the requirements for a released BSP that conform to the 1232 Following are the requirements for a released BSP
1219 Yocto Project: 1233 that conform to the Yocto Project:
1220 <itemizedlist> 1234 <itemizedlist>
1221 <listitem><para><emphasis>Layer Name:</emphasis> 1235 <listitem><para>
1222 The BSP must have a layer name that follows the Yocto 1236 <emphasis>Layer Name:</emphasis>
1223 Project standards. 1237 The BSP must have a layer name that follows
1238 the Yocto Project standards.
1224 For information on BSP layer names, see the 1239 For information on BSP layer names, see the
1225 "<link linkend='bsp-layers'>BSP Layers</link>" section. 1240 "<link linkend='bsp-layers'>BSP Layers</link>" section.
1226 </para></listitem> 1241 </para></listitem>
1227 <listitem><para><emphasis>File System Layout:</emphasis> 1242 <listitem><para>
1228 When possible, use the same directory names in your 1243 <emphasis>File System Layout:</emphasis>
1229 BSP layer as listed in the <filename>recipes.txt</filename> file. 1244 When possible, use the same directory names
1230 In particular, you should place recipes 1245 in your BSP layer as listed in the
1231 (<filename>.bb</filename> files) and recipe 1246 <filename>recipes.txt</filename> file, which
1232 modifications (<filename>.bbappend</filename> files) into 1247 is found in <filename>poky/meta</filename>
1233 <filename>recipes-*</filename> subdirectories by functional area 1248 directory of the
1234 as outlined in <filename>recipes.txt</filename>. 1249 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
1235 If you cannot find a category in <filename>recipes.txt</filename>
1236 to fit a particular recipe, you can make up your own
1237 <filename>recipes-*</filename> subdirectory.
1238 You can find <filename>recipes.txt</filename> in the
1239 <filename>meta</filename> directory of the
1240 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>,
1241 or in the OpenEmbedded Core Layer 1250 or in the OpenEmbedded Core Layer
1242 (<filename>openembedded-core</filename>) found at 1251 (<filename>openembedded-core</filename>) at
1243 <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>. 1252 <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>.
1244 </para> 1253 </para>
1245 <para>Within any particular <filename>recipes-*</filename> category, the layout 1254
1246 should match what is found in the OpenEmbedded Core 1255 <para>You should place recipes
1247 Git repository (<filename>openembedded-core</filename>) 1256 (<filename>*.bb</filename> files) and recipe
1257 modifications (<filename>*.bbappend</filename>
1258 files) into <filename>recipes-*</filename>
1259 subdirectories by functional area as outlined
1260 in <filename>recipes.txt</filename>.
1261 If you cannot find a category in
1262 <filename>recipes.txt</filename> to fit a
1263 particular recipe, you can make up your own
1264 <filename>recipes-*</filename> subdirectory.
1265 </para>
1266
1267 <para>Within any particular
1268 <filename>recipes-*</filename> category, the
1269 layout should match what is found in the
1270 OpenEmbedded Core Git repository
1271 (<filename>openembedded-core</filename>)
1248 or the Source Directory (<filename>poky</filename>). 1272 or the Source Directory (<filename>poky</filename>).
1249 In other words, make sure you place related files in appropriately 1273 In other words, make sure you place related
1250 related <filename>recipes-*</filename> subdirectories specific to the 1274 files in appropriately related
1251 recipe's function, or within a subdirectory containing a set of closely-related 1275 <filename>recipes-*</filename> subdirectories
1276 specific to the recipe's function, or within
1277 a subdirectory containing a set of closely-related
1252 recipes. 1278 recipes.
1253 The recipes themselves should follow the general guidelines 1279 The recipes themselves should follow the general
1254 for recipes used in the Yocto Project found in the 1280 guidelines for recipes used in the Yocto Project
1281 found in the
1255 "<ulink url='http://openembedded.org/wiki/Styleguide'>OpenEmbedded Style Guide</ulink>". 1282 "<ulink url='http://openembedded.org/wiki/Styleguide'>OpenEmbedded Style Guide</ulink>".
1256 </para></listitem> 1283 </para></listitem>
1257 <listitem><para><emphasis>License File:</emphasis> 1284 <listitem><para>
1285 <emphasis>License File:</emphasis>
1258 You must include a license file in the 1286 You must include a license file in the
1259 <filename>meta-<replaceable>bsp_name</replaceable></filename> directory. 1287 <filename>meta-</filename><replaceable>bsp_name</replaceable>
1288 directory.
1260 This license covers the BSP Metadata as a whole. 1289 This license covers the BSP Metadata as a whole.
1261 You must specify which license to use since there is no 1290 You must specify which license to use since no
1262 default license if one is not specified. 1291 default license exists when one not specified.
1263 See the 1292 See the
1264 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/COPYING.MIT'><filename>COPYING.MIT</filename></ulink> 1293 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/COPYING.MIT'><filename>COPYING.MIT</filename></ulink>
1265 file for the Raspberry Pi BSP in the 1294 file for the Raspberry Pi BSP in the
1266 <filename>meta-raspberrypi</filename> BSP layer as an example. 1295 <filename>meta-raspberrypi</filename> BSP layer
1296 as an example.
1267 </para></listitem> 1297 </para></listitem>
1268 <listitem><para><emphasis>README File:</emphasis> 1298 <listitem><para>
1269 You must include a <filename>README</filename> file in the 1299 <emphasis>README File:</emphasis>
1270 <filename>meta-<replaceable>bsp_name</replaceable></filename> directory. 1300 You must include a <filename>README</filename>
1301 file in the
1302 <filename>meta-</filename><replaceable>bsp_name</replaceable>
1303 directory.
1271 See the 1304 See the
1272 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README'><filename>README</filename></ulink> 1305 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README'><filename>README</filename></ulink>
1273 file for the Raspberry Pi BSP in the <filename>meta-raspberrypi</filename> BSP layer 1306 file for the Raspberry Pi BSP in the
1307 <filename>meta-raspberrypi</filename> BSP layer
1274 as an example.</para> 1308 as an example.</para>
1275 <para>At a minimum, the <filename>README</filename> file should 1309
1276 contain the following: 1310 <para>At a minimum, the <filename>README</filename>
1311 file should contain the following:
1277 <itemizedlist> 1312 <itemizedlist>
1278 <listitem><para>A brief description about the hardware the BSP 1313 <listitem><para>
1279 targets.</para></listitem> 1314 A brief description about the hardware the BSP
1280 <listitem><para>A list of all the dependencies 1315 targets.
1316 </para></listitem>
1317 <listitem><para>
1318 A list of all the dependencies
1281 on which a BSP layer depends. 1319 on which a BSP layer depends.
1282 These dependencies are typically a list of required layers needed 1320 These dependencies are typically a list
1283 to build the BSP. 1321 of required layers needed to build the
1284 However, the dependencies should also contain information regarding 1322 BSP.
1285 any other dependencies the BSP might have.</para></listitem> 1323 However, the dependencies should also
1286 <listitem><para>Any required special licensing information. 1324 contain information regarding any other
1287 For example, this information includes information on 1325 dependencies the BSP might have.
1288 special variables needed to satisfy a EULA, 1326 </para></listitem>
1289 or instructions on information needed to build or distribute 1327 <listitem><para>
1290 binaries built from the BSP Metadata.</para></listitem> 1328 Any required special licensing information.
1291 <listitem><para>The name and contact information for the 1329 For example, this information includes
1330 information on special variables needed
1331 to satisfy a EULA, or instructions on
1332 information needed to build or distribute
1333 binaries built from the BSP Metadata.
1334 </para></listitem>
1335 <listitem><para>
1336 The name and contact information for the
1292 BSP layer maintainer. 1337 BSP layer maintainer.
1293 This is the person to whom patches and questions should 1338 This is the person to whom patches and
1294 be sent. 1339 questions should be sent.
1295 For information on how to find the right person, see the 1340 For information on how to find the right
1341 person, see the
1296 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>" 1342 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
1297 section in the Yocto Project Development Tasks Manual. 1343 section in the Yocto Project Development
1344 Tasks Manual.
1298 </para></listitem> 1345 </para></listitem>
1299 <listitem><para>Instructions on how to build the BSP using the BSP 1346 <listitem><para>
1300 layer.</para></listitem> 1347 Instructions on how to build the BSP using
1301 <listitem><para>Instructions on how to boot the BSP build from 1348 the BSP layer.
1302 the BSP layer.</para></listitem> 1349 </para></listitem>
1303 <listitem><para>Instructions on how to boot the binary images 1350 <listitem><para>
1304 contained in the <filename>binary</filename> directory, 1351 Instructions on how to boot the BSP build
1305 if present.</para></listitem> 1352 from the BSP layer.
1306 <listitem><para>Information on any known bugs or issues that users 1353 </para></listitem>
1307 should know about when either building or booting the BSP 1354 <listitem><para>
1308 binaries.</para></listitem> 1355 Instructions on how to boot the binary
1309 </itemizedlist></para></listitem> 1356 images contained in the
1310 <listitem><para><emphasis>README.sources File:</emphasis> 1357 <filename>binary</filename> directory,
1311 You must include a <filename>README.sources</filename> in the 1358 if present.
1312 <filename>meta-<replaceable>bsp_name</replaceable></filename> directory. 1359 </para></listitem>
1313 This file specifies exactly where you can find the sources used to 1360 <listitem><para>
1314 generate the binary images contained in the 1361 Information on any known bugs or issues
1315 <filename>binary</filename> directory, if present. 1362 that users should know about when either
1363 building or booting the BSP binaries.
1364 </para></listitem>
1365 </itemizedlist>
1316 </para></listitem> 1366 </para></listitem>
1317 <listitem><para><emphasis>Layer Configuration File:</emphasis> 1367 <listitem><para>
1318 You must include a <filename>conf/layer.conf</filename> in the 1368 <emphasis>README.sources File:</emphasis>
1319 <filename>meta-<replaceable>bsp_name</replaceable></filename> directory. 1369 If you BSP contains binary images in the
1320 This file identifies the <filename>meta-<replaceable>bsp_name</replaceable></filename> 1370 <filename>binary</filename> directory, you must
1321 BSP layer as a layer to the build system.</para></listitem> 1371 include a <filename>README.sources</filename>
1322 <listitem><para><emphasis>Machine Configuration File:</emphasis> 1372 file in the
1373 <filename>meta-</filename><replaceable>bsp_name</replaceable>
1374 directory.
1375 This file specifies exactly where you can find
1376 the sources used to generate the binary images.
1377 </para></listitem>
1378 <listitem><para>
1379 <emphasis>Layer Configuration File:</emphasis>
1380 You must include a
1381 <filename>conf/layer.conf</filename> file in
1382 the
1383 <filename>meta-</filename><replaceable>bsp_name</replaceable>
1384 directory.
1385 This file identifies the
1386 <filename>meta-</filename><replaceable>bsp_name</replaceable>
1387 BSP layer as a layer to the build system.
1388 </para></listitem>
1389 <listitem><para>
1390 <emphasis>Machine Configuration File:</emphasis>
1323 You must include one or more 1391 You must include one or more
1324 <filename>conf/machine/<replaceable>bsp_name</replaceable>.conf</filename> 1392 <filename>conf/machine/</filename><replaceable>bsp_name</replaceable><filename>.conf</filename>
1325 files in the <filename>meta-<replaceable>bsp_name</replaceable></filename> directory. 1393 files in the
1326 These configuration files define machine targets that can be built 1394 <filename>meta-</filename><replaceable>bsp_name</replaceable>
1327 using the BSP layer. 1395 directory.
1328 Multiple machine configuration files define variations of machine 1396 These configuration files define machine targets
1329 configurations that are supported by the BSP. 1397 that can be built using the BSP layer.
1330 If a BSP supports multiple machine variations, you need to 1398 Multiple machine configuration files define
1331 adequately describe each variation in the BSP 1399 variations of machine configurations that the
1332 <filename>README</filename> file. 1400 BSP supports.
1333 Do not use multiple machine configuration files to describe disparate 1401 If a BSP supports multiple machine variations,
1334 hardware. 1402 you need to adequately describe each variation
1335 If you do have very different targets, you should create separate 1403 in the BSP <filename>README</filename> file.
1336 BSP layers for each target. 1404 Do not use multiple machine configuration files
1337 <note>It is completely possible for a developer to structure the 1405 to describe disparate hardware.
1338 working repository as a conglomeration of unrelated BSP 1406 If you do have very different targets, you should
1339 files, and to possibly generate BSPs targeted for release 1407 create separate BSP layers for each target.
1340 from that directory using scripts or some other mechanism 1408 <note>
1341 (e.g. <filename>meta-yocto-bsp</filename> layer). 1409 It is completely possible for a developer to
1342 Such considerations are outside the scope of this document.</note> 1410 structure the working repository as a
1411 conglomeration of unrelated BSP files, and to
1412 possibly generate BSPs targeted for release
1413 from that directory using scripts or some
1414 other mechanism
1415 (e.g. <filename>meta-yocto-bsp</filename> layer).
1416 Such considerations are outside the scope of
1417 this document.
1418 </note>
1343 </para></listitem> 1419 </para></listitem>
1344 </itemizedlist> 1420 </itemizedlist>
1345 </para> 1421 </para>