Coverage for apio/commands/apio_upload.py: 80%

1# This file is part of the Apio project 

2# (C) 2016-present FPGAwars 

3# Project authors: 

4# * Jesús Arroyo (Jesus89) (2016-2019) 

5# * Juan Gonzalez (obijuan) (2019-2024) 

6# * The Apio Team (2024-present) 

7# License: GPLv2 

8 

9"""Implementation of 'apio upload' command""" 

10 

11import sys 

12from pathlib import Path 

13import click 

14from apio.managers.scons_manager import SConsManager 

15from apio.utils import cmd_util 

16from apio.commands import options 

17from apio.apio_context import ( 

18 ApioContext, 

19 PackagesPolicy, 

20 ProjectPolicy, 

21 RemoteConfigPolicy, 

22) 

23from apio.managers.programmers import construct_programmer_cmd 

24from apio.common.proto.stubs.apio_scons_pb2 import UploadParams 

25 

26 

27# --------- apio upload 

28 

29serial_port_option = click.option( 

30 "serial_port", # Var name. 

31 "-s", 

32 "--serial-port", 

33 type=str, 

34 metavar="serial-port", 

35 help="Set the serial port.", 

36 cls=cmd_util.ApioOption, 

37) 

38 

39serial_num_option = click.option( 

40 "serial_num", # Var name. 

41 "-n", 

42 "--serial-num", 

43 type=str, 

44 metavar="serial-num", 

45 help="Select the device's USB serial number.", 

46 cls=cmd_util.ApioOption, 

47) 

48 

49 

50# -- Text in the rich-text format of the python rich library. 

51APIO_UPLOAD_HELP = """ 

52The command 'apio upload' builds the bitstream file (similar to the \ 

53'apio build' command) and uploads it to the FPGA board. 

54 

55Examples:[code] 

56 apio upload # Typical invocation 

57 apio upload -s /dev/cu.usbserial-1300 # Select serial port 

58 apio upload -n FTXYA34Z # Select serial number[/code] 

59 

60Typically the simple form 'apio upload' is sufficient to locate and program \ 

61the FPGA board. The optional flags '--serial-port' and '--serial-num' allows \ 

62to select the desired board if more than one matching board is detected. 

63 

64[HINT] You can use the command 'apio devices' to list the connected USB and \ 

65serial devices and the command 'apio drivers' to install and uninstall device \ 

66drivers. 

67 

68[HINT] The default programmer command of your board can be overridden using \ 

69the apio.ini option 'programmer-cmd'. 

70""" 

71 

72 

73@click.command( 

74 name="upload", 

75 cls=cmd_util.ApioCommand, 

76 short_help="Upload the bitstream to the FPGA.", 

77 help=APIO_UPLOAD_HELP, 

78) 

79@click.pass_context 

80@serial_port_option 

81@serial_num_option 

82@options.env_option_gen() 

83@options.project_dir_option 

84def cli( 

85 _: click.Context, 

86 *, 

87 # Options 

88 serial_port: str, 

89 serial_num: str, 

90 env: str | None, 

91 project_dir: Path | None, 

92): 

93 """Implements the upload command.""" 

94 

95 # -- Create a apio context. 

96 apio_ctx = ApioContext( 

97 project_policy=ProjectPolicy.PROJECT_REQUIRED, 

98 remote_config_policy=RemoteConfigPolicy.CACHED_OK, 

99 packages_policy=PackagesPolicy.ENSURE_PACKAGES, 

100 project_dir_arg=project_dir, 

101 env_arg=env, 

102 ) 

103 

104 # -- Get the programmer command. 

105 programmer_cmd = construct_programmer_cmd( 

106 apio_ctx, serial_port_flag=serial_port, serial_num_flag=serial_num 

107 ) 

108 

109 # Construct the scons upload params. 

110 upload_params = UploadParams(programmer_cmd=programmer_cmd) 

111 

112 # -- Create the scons manager 

113 scons = SConsManager(apio_ctx) 

114 

115 # Run scons: upload command 

116 exit_code = scons.upload(upload_params) 

117 

118 # -- Done! 

119 sys.exit(exit_code)